.\" Copyright (c) 2007-2019 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd November 16, 2007
.Dt AG_THREADS 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.3
.Sh NAME
.Nm AG_Threads
.Nd agar threads support
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
.Ed
.Sh DESCRIPTION
On all platforms with threads support, Agar can be compiled with support for
multithreading.
Agar API calls, unless otherwise documented, then become
.Em free-threaded
(safe to use from different threads without need for application-level
synchronization).
.Sh CONVENTIONS
The Agar API documentation follows the convention that all functions are
free-threaded, unless mentioned otherwise.
.Pp
Under some circumstances, application-level synchronization is required.
The
.Xr AG_Object 3
simplifies this task by providing a per-object lock (which is implicitely
acquired in some contexts, such as event handler execution).
For instance, the following code accesses a VFS in an unsafe manner:
.Bd -literal -offset indent
AG_Object *o;

o = AG_ObjectFind(root, "/Foo");
if (o != NULL) { ... }			/* UNSAFE */
.Ed
.Pp
The following code should be used instead:
.Bd -literal -offset indent
AG_Object *o;

AG_ObjectLock(root);
o = AG_ObjectFind(root, "/Foo");
if (o != NULL) { ... }			/* Safe access */
AG_ObjectUnlock(root);
.Ed
.Sh THREADS INTERFACE
When compiled with threads support, Agar provides a portable, minimal interface
to the operating system's native threads interface.
These functions follow Agar's standard error-handling style (see
.Xr AG_Intro 3 ) .
.Sh MUTEXES
.\" MANLINK(AG_Mutex)
Mutexes (MUTual EXclusion devices) are commonly used to protect shared
data structure against concurrent modifications.
.Pp
.nr nS 1
.Ft "void"
.Fn AG_MutexInit "AG_Mutex *mutex"
.Pp
.Ft "int"
.Fn AG_MutexTryInit "AG_Mutex *mutex"
.Pp
.Ft "void"
.Fn AG_MutexInitRecursive "AG_Mutex *mutex"
.Pp
.Ft "int"
.Fn AG_MutexTryInitRecursive "AG_Mutex *mutex"
.Pp
.Ft "void"
.Fn AG_MutexDestroy "AG_Mutex *mutex"
.Pp
.Ft "void"
.Fn AG_MutexLock "AG_Mutex *mutex"
.Pp
.Ft "int"
.Fn AG_MutexTryLock "AG_Mutex *mutex"
.Pp
.Ft "void"
.Fn AG_MutexUnlock "AG_Mutex *mutex"
.Pp
.nr nS 0
The
.Fn AG_MutexInit
function initializes a mutex structure.
.Fn AG_MutexInitRecursive
initializes a recursive mutex (a mutex with a reference count),
which allows nested
.Fn AG_MutexLock
calls.
.Pp
.Fn AG_MutexDestroy
frees all resources allocated for a mutex.
.Pp
.Fn AG_MutexLock
and
.Fn AG_MutexUnlock
respectively acquire and release a mutex.
.Pp
.Fn AG_MutexTryLock
tries to acquire a mutex without blocking and immediately returns 0 on
success.
On failure, the function returns -1, but does not set any error message (so
.Xr AG_GetError 3
should not be used).
.Sh CONDITION VARIABLES
.\" MANLINK(AG_Cond)
.nr nS 1
.Ft "void"
.Fn AG_CondInit "AG_Cond *cv"
.Pp
.Ft "int"
.Fn AG_CondTryInit "AG_Cond *cv"
.Pp
.Ft "void"
.Fn AG_CondDestroy "AG_Cond *cv"
.Pp
.Ft "void"
.Fn AG_CondBroadcast "AG_Cond *cv"
.Pp
.Ft "void"
.Fn AG_CondSignal "AG_Cond *cv"
.Pp
.Ft "int"
.Fn AG_CondWait "AG_Cond *cv" "AG_Mutex *m"
.Pp
.Ft "int"
.Fn AG_CondTimedWait "AG_Cond *cv" "AG_Mutex *m" "const struct timespec *t"
.Pp
.nr nS 0
.Fn AG_CondInit
initializes a condition variable structure.
.Pp
.Fn AG_CondDestroy
releases resources allocated for a condition variable.
.Pp
.Fn AG_CondBroadcast
unblock all threads which are currently blocked waiting on
.Fa cv .
.Fn AG_CondSignal
unblocks at least one thread currently blocked waiting on
.Fa cv .
.Pp
.Fn AG_CondWait
blocks the calling thread until
.Fa cv
is signaled.
The
.Fn AG_CondTimedWait
variant will not block for more than the specified amount of time.
.Pp
All of these functions will raise a fatal condition if an error is encountered.
.Sh THREADS
.\" MANLINK(AG_Thread)
.nr nS 1
.Ft void
.Fn AG_ThreadCreate "AG_Thread *th" "void *(*fn)(void *arg)" "void *arg"
.Pp
.Ft int
.Fn AG_ThreadTryCreate "AG_Thread *th" "void *(*fn)(void *arg)" "void *arg"
.Pp
.Ft void
.Fn AG_ThreadCancel "AG_Thread th"
.Pp
.Ft int
.Fn AG_ThreadTryCancel "AG_Thread th"
.Pp
.Ft void
.Fn AG_ThreadJoin "AG_Thread th" "void **exitVal"
.Pp
.Ft int
.Fn AG_ThreadTryJoin "AG_Thread th" "void **exitVal"
.Pp
.Ft void
.Fn AG_ThreadExit "void *exitVal"
.Pp
.Ft void
.Fn AG_ThreadKill "AG_Thread th" "int signal"
.Pp
.Ft AG_Thread
.Fn AG_ThreadSelf "void"
.Pp
.Ft int
.Fn AG_ThreadEqual "AG_Thread a" "AG_Thread b"
.Pp
.nr nS 0
.Fn AG_ThreadCreate
creates a new thread executing
.Fa fn .
The optional argument
.Fa arg
is passed to
.Fa fn .
.Pp
The
.Fn AG_ThreadCancel
routine requests that the specified thread be cancelled.
If the given thread is invalid, a fatal error is raised.
.Pp
The
.Fn AG_ThreadJoin
function suspends the execution of the current thread until
.Fa th
terminates.
When it does, the value passed to
.Fn AG_ThreadExit
is made available in
.Fa exitVal .
.Pp
.Fn AG_ThreadExit
terminates the current thread.
.Fa exitVal
is an optional user pointer.
.Pp
.Fn AG_ThreadKill
sends a signal to the specified thread.
.Pp
.Fn AG_ThreadSelf
returns the identifier of the current (caller's) thread.
.Fn AG_ThreadEqual
returns 1 if the identifiers
.Fa a
and
.Fa b
both refer to the same thread, or 0 if they differ.
.Sh THREAD-SPECIFIC VARIABLES
.nr nS 1
.\" MANLINK(AG_ThreadKey)
.Ft void
.Fn AG_ThreadKeyCreate "AG_ThreadKey *key" "void (*destructor)(void *)"
.Pp
.Ft int
.Fn AG_ThreadKeyTryCreate "AG_ThreadKey *key" "void (*destructor)(void *)"
.Pp
.Ft void
.Fn AG_ThreadKeyDelete "AG_ThreadKey key"
.Pp
.Ft int
.Fn AG_ThreadKeyTryDelete "AG_ThreadKey key"
.Pp
.Ft "void *"
.Fn AG_ThreadKeyGet "AG_ThreadKey key"
.Pp
.Ft "void"
.Fn AG_ThreadKeySet "AG_ThreadKey key" "const void *value"
.Pp
.Ft "int"
.Fn AG_ThreadKeyTrySet "AG_ThreadKey key" "const void *value"
.Pp
.nr nS 0
.Fn AG_ThreadKeyCreate
initializes a key (i.e., a handle) to a thread-specific value.
The handle itself is accessible to all threads.
The thread-specific value (i.e., the value specified by
.Fn AG_ThreadKeySet ,
and which defaults to NULL) will persist only for the life of the thread.
If an optional
.Fa destructor
is given, that function will be called (with the thread-specific value as
its argument), when the thread exists.
.Pp
The
.Fn AG_ThreadKeyDelete
function releases resources allocated for a key.
.Pp
.Fn AG_ThreadKeyGet
returns the thread-specific value associated with
.Fa key .
.Pp
.Fn AG_ThreadKeySet
sets a thread-specific value with
.Fa key .
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Object 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.0
